package com.tripcube.ai.model.vo;

import lombok.Data;
import io.swagger.v3.oas.annotations.media.Schema;
import java.util.List;

/**
 * 知识库检索结果视图对象
 * 
 * @author alander
 */
@Data
@Schema(description = "知识库检索结果")
public class KnowledgeRetrievalVO {

    /**
     * 检索结果列表
     * 包含所有匹配的文档项，按相似度分数排序
     */
    @Schema(description = "检索结果列表")
    private List<RetrievalItem> items;

    /**
     * 总数量
     * 检索到的文档总数量
     */
    @Schema(description = "总数量")
    private Integer total;

    /**
     * 检索耗时（毫秒）
     * 本次检索操作的总耗时，用于性能监控
     */
    @Schema(description = "检索耗时（毫秒）")
    private Long duration;

    /**
     * 检索结果项
     * 
     * 表示单个检索到的文档项，包含文档基本信息、
     * 相关内容片段、相似度分数等详细信息。
     */
    @Data
    @Schema(description = "检索结果项")
    public static class RetrievalItem {

        /**
         * 文档ID
         * 文档的唯一标识符，对应数据库中的文档记录
         */
        @Schema(description = "文档ID")
        private String documentId; // Maps to DocId

        /**
         * 文档名称
         * 文档的显示名称或标题
         */
        @Schema(description = "文档名称")
        private String documentName; // Maps to DocName

        /**
         * 相关内容
         * 与查询相关的文档内容片段
         */
        @Schema(description = "相关内容")
        private String content; // Maps to Text

        /**
         * 相似度分数
         * 文档与查询的相似度分数，范围通常为0-1
         */
        @Schema(description = "相似度分数")
        private Double score; // Maps to Score

        /**
         * 元数据
         * 文档的附加元数据信息，如标签、分类等
         */
        private Object metadata;
    }
}